Notifications — Payment acceptance via the YooMoney API

Notifications

If you'd like to keep track of the status of objects (for example, of payments and refunds), you can subscribe to notifications (webhook, callback) about such events.

Notifications are useful for cases when the API object changes without your participation, for example, if the user needs to confirm the payment, the payment process might take from a few minutes to several hours. Instead of sending periodic GET requests for the duration of this period, you can just wait for a YooMoney notification to learn about the status.

The events that you can track depend on the payment solution that you're using. The method of configuration of the notifications depends on the method of authentication of requests.

About events in YooMoney

Changes in the status of objects are considered events in YooMoney. You can track the events for payments, refunds, payouts, and deals.

The events that you can subscribe to depend on the payment solution that you use (for example regular payments, Safe Deal, Partnership program). To track events, subscribe to them.

As soon as an event you're subscribed to occurs, you receive a notification. You need to confirm that you've received it. The notification will contain all the information about the object at the time when the status has changed. More about using notifications

The name of the event is generated from the <object>.<status> template, consisting of two parts:

object originating the event: payment, refund, payout, deal;
status acquired by the object, for example succeeded or canceled. Learn more about statuses for different objects in the API Reference .

Example: payment.succeeded means the payment status was changed to succeeded.

Available events

Event	Payments	Payouts	Split payments, Partnership program	Safe deal
Payments
payment.waiting_for_capture	✅	❌	✅	✅
payment.succeeded	✅	❌	✅	✅
payment.canceled	✅	❌	✅	✅
Refunds
refund.succeeded	✅	❌	✅	✅
Payouts
payout.succeeded	❌	✅	❌	✅
payout.canceled	❌	✅	❌	✅
Deals
deal.closed	❌	❌	❌	✅

Configuration

YooMoney offers two methods of configuring notifications depending on the method of request authentication:

If you use HTTP Basic Auth, you will need to configure notifications in the Merchant Profile.
If you use OAuth, you can only configure notifications via the API.

For payment solutions with HTTP Basic Auth

If you use the payment solution with HTTP Basic Auth (regular payments, payouts, Split payments, Safe deal), you can subscribe to notifications from YooMoney in the Merchant Profile.

Specify the URL for notifications and events you want to track in the Integration — HTTP-notifications section.

The HTTPS protocol and TCP port 443 or 8443 must be used in the URL for notifications. Any TLS/SSL certificate is applicable: either self-signed or issued by the certificate authority. Supported TLS/SSL versions: 1.2 or higher.

To unsubscribe from notifications, disable the unrequired events in the Integration — HTTP notifications section.

For the partnership program (OAuth)

If you’re taking part in the YooMoney for Business partnership program, you’ll need to subscribe to notifications via API.

You can only track events for payments and refunds. Create a webhook object for every event you want to track by specifying the event you want to subscribe to as well as the URL for notifications in the request .

Notifications will only be sent for objects created by your app.

You’ll need to create a separate set of webhooks for each OAuth token.

Example of a request for creating a webhook object

cURL
PHP
Python
curl https://api.yookassa.ru/v3/webhooks \
  -X POST \
  -H 'Authorization: Bearer <oauth_token>' \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "event": "payment.succeeded",
        "url": "https://www.example.com/notification_url"
      }'

Example of the response body

JSON
{
  "id": "wh-e44e8088-bd73-43b1-959a-954f3a7d0c54",
  "event": "payment.succeeded",
  "url": "https://www.example.com/notification_url"
}

You can view the list of tracked events and remoove the ones you don’t need.

To unsubscribe from notifications about an event for a sent OAuth token, remove the corresponding webhook object by specifying its identifier in the request .

Implementation

After an event you’re subscribed to occurs, a notification will be sent to the URL that you specified during configuration.

Notification body parameters

Parameter	Type	Description
type	string	Object type. Fixed value: `notification`. Required parameter
event	string	Event that YooMoney notifies about. Example: `payment.waiting_for_capture`. Required parameter
object	object	Object that was affected by the specified event. For example, if `payment.waiting_for_capture` is specified in the `event` parameter, the `object` parameter will contain the payment object whose status changed to `waiting_for_capture`. The object will contain all the details relevant at the time of the event. Object parameters are provided in the API Reference . Required parameter

Example of the payment.waiting_for_capture notification body

JSON
{
  "type": "notification",
  "event": "payment.waiting_for_capture",
  "object": {
    "id": "22d6d597-000f-5000-9000-145f6df21d6f",
    "status": "waiting_for_capture",
    "paid": true,
    "amount": {
      "value": "2.00",
      "currency": "RUB"
    },
    "authorization_details": {
      "rrn": "10000000000",
      "auth_code": "000000",
      "three_d_secure": {
        "applied": true
      }
    },
    "created_at": "2018-07-10T14:27:54.691Z",
    "description": "Order No. 72",
    "expires_at": "2018-07-17T14:28:32.484Z",
    "metadata": {},
    "payment_method": {
      "type": "bank_card",
      "id": "22d6d597-000f-5000-9000-145f6df21d6f",
      "saved": false,
      "card": {
        "first6": "555555",
        "last4": "4444",
        "expiry_month": "07",
        "expiry_year": "2021",
        "card_type": "MasterCard",
      "issuer_country": "RU",
      "issuer_name": "Sberbank"
      },
      "title": "Bank card *4444"
    },
    "refundable": false,
    "test": false
  }
}

You will need to confirm that you’ve received the notification. Reply with HTTP 200 code. YooMoney will ignore everything specified in the body or header of the response. Responses containing any other HTTP codes are considered invalid, and YooMoney will continue sending out the notification for the next 24 hours following the moment when the event occurred.

Notification authentication

You can check the authenticity of a notification, for example, by the object status or IP address. This will help you defend yourself against attacks based on fake notifications.

Object status authentication

Check the current status of the object to ensure that the status in the notification is up-to-date.

IP authentication

Check the IP address that the notification was sent from. YooMoney can send notifications from any of the following IP addresses:

185.71.76.0/27
185.71.77.0/27
77.75.153.0/25
77.75.156.11
77.75.156.35
77.75.154.128/25
2a02:5180::/32

Processing via SDKs

You can process notifications using our server SDKs:

Obtain data from a POST request made by YooMoney.
Create a notification class object depending on the event.
Obtain the Payment object.

Example of processing notifications using an SDK

PHP
Python
// Obtain data from a POST request made by YooMoney

<?php
    $source = file_get_contents('php://input');
    $requestBody = json_decode($source, true);
?>

// Create a notification class object depending on the event
// NotificationSucceeded, NotificationWaitingForCapture,
// NotificationCanceled,  NotificationRefundSucceeded

<?php
    use YooKassa\Model\Notification\NotificationSucceeded;
    use YooKassa\Model\Notification\NotificationWaitingForCapture;
    use YooKassa\Model\NotificationEventType;

    try {
      $notification = ($requestBody['event'] === NotificationEventType::PAYMENT_SUCCEEDED)
        ? new NotificationSucceeded($requestBody)
        : new NotificationWaitingForCapture($requestBody);
    } catch (Exception $e) {
        // Processing errors
    }
?>

// Obtain the Payment object

<?php
    $payment = $notification->getObject();
?>

Handling YooMoney widget events

The YooMoney widget has its own events about which it can send notifications. You can handle these events to interact with the user after the payment is finished or after the pop-up window with the payment form gets closed.